V2 Spec Additions #945

olaservo · 2025-11-30T14:02:17Z

Fixes: #947

Changes:

Adds a spec file for UX
Adds my takes on which tech to use for http and logging

Methodology:

Used Claude Opus 4.5 to analyze MCPJam source and latest MCP spec schema to propose UX and features to add to current spec files
Started grabbing a few feature requests ad-hoc from current inspector issues that seem like they should be included (such as support for official registry server.json)

Other notes:

I think it would be ideal to get something interactive going early, so I am generating a couple simple prototypes to get a feel for what the code would actually look like and how it might work in practice. Will post those in the discord and latest WG discussion thread.
If that method works well, we can let claude [or insert your fav bot here] to pick and choose what we like from those examples and use that to iterate on the spec.

- Express: cleaner routing/middleware for proxy CRUD endpoints, well-maintained ecosystem - Pino: fastest logger option, JSON-structured logs work well for debugging MCP traffic 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Based on MCPJam Inspector analysis: - Server connection card with status indicators - Resizable panel layouts for Tools/Resources/Prompts screens - Form generation from JSON Schema - Error handling patterns (inline errors, retry count, doc links) Also updates nav links in all spec files to include v2_ux.md. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

- Add server.json import support (Issue modelcontextprotocol#922) for MCP Registry format - Add History Screen with automatic capture and replay functionality - Add Pino logging rationale with log-as-history architecture - Remove emojis from markdown files, use text alternatives New UX sections added: - Logging Screen (notifications/message, logging/setLevel) - Tasks Screen (tasks/*, notifications/task/statusChanged) - Sampling Panel (sampling/createMessage) - Elicitation Handler (form + URL modes) - Roots Configuration (roots/list) - Experimental Features Panel (raw JSON-RPC tester) Enhanced existing screens: - Tools: annotations, autocomplete, progress indicators, image/audio - Resources: annotations, subscriptions - Prompts: autocomplete - Navigation: ping latency, listChanged indicators 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Implements UI-only prototype for component library evaluation: - Server List home page with server cards - AppLayout with top navigation (Tools, Resources, Prompts, Logs, Tasks, History) - All 7 screen stubs with mock data - ServerCard and StatusIndicator components - Dark theme with Mantine v7 Based on v2_ux.md specification from PR modelcontextprotocol#945. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

Implements UI-only prototype for component library evaluation: - Server List home page with server cards - AppLayout with top navigation (Tools, Resources, Prompts, Logs, Tasks, History) - All 7 screen stubs with mock data - ServerCard and StatusIndicator components - Shadcn UI components (Button, Card, Badge, Switch, Input, Select) - Tailwind CSS dark theme Based on v2_ux.md specification from PR modelcontextprotocol#945. Mirror of Mantine prototype for comparison. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>

cliffhall

Thanks for all this great work, @olaservo. I added a few thoughts.

cliffhall · 2025-12-02T19:09:09Z

specification/v2_ux.md

+│   [user]               │                                                  │
+│                         │ {                                               │
+│ ○ data.csv              │   "name": "my-app",                             │
+│                         │   "version": "1.0.0"                            │


Perhaps we can split this left pane to have dynamically up to three scrollable regions. If there are only resources, they take up the whole pane. If there are also templates, the pane is split in two. When there are subscriptions, another pane could be added for them.

cliffhall · 2025-12-02T19:10:19Z

specification/v2_ux.md

+│ ☑ DEBUG              │                                                  │
+│ ☑ INFO               │                                                  │
+│ ☑ WARNING            │                                                  │
+│ ☑ ERROR              │                                                  │


All the available levels aren't represented here.

cliffhall · 2025-12-02T19:10:58Z

specification/v2_ux.md

+  - DEBUG: gray
+  - INFO: blue
+  - WARNING: yellow
+  - ERROR: red


Need colors (or shades) for all levels (debug, info, notice, warning, error, critical, alert, emergency)

cliffhall · 2025-12-02T19:13:31Z

specification/v2_ux.md

+- Display server's experimental capabilities from initialization
+- Toggle client experimental capabilities to advertise
+- Add custom client experimental capabilities
+- **Raw JSON-RPC Tester:**


What if the experimental feature requires custom headers?

cliffhall · 2025-12-02T19:18:58Z

specification/v2_ux.md

+| JSON Schema Type | Form Control |
+|------------------|--------------|
+| `string` | Text input |
+| `string` (enum) | Select dropdown |


With the new spec, we have single select and multi-select enums. The component framework we use will need to support multi-select combobox/select component or we could use checkboxes.

For instance shadcn has both combobox and select, but neither support multiselect, but there is a third party component that does: https://shadcn-multi-select-component.vercel.app/

cliffhall · 2025-12-02T19:36:21Z

specification/v2_ux.md

+├─────────────────────────────────────────────────────────┤
+│ npx -y @modelcontextprotocol/server-everything    [Copy]│
+├─────────────────────────────────────────────────────────┤
+│ [Server Info]                          [Edit] [Remove]  │


Another thing from the sidebar that hasn't found a home is timeout behavior. That may be something that should be server specific as well. Perhaps we add a [Timeouts] button/modal?

cliffhall · 2025-12-02T19:36:38Z

specification/v2_ux.md

+├─────────────────────────────────────────────────────────┤
+│ npx -y @modelcontextprotocol/server-everything    [Copy]│
+├─────────────────────────────────────────────────────────┤
+│ [Server Info]                          [Edit] [Remove]  │


Based on the three above comments, we might also want a [Clone] button for the server card as well, so that it could be configured in different ways, with different headers, metadata, timeouts.

cliffhall · 2025-12-02T19:39:35Z

specification/v2_ux.md

+├─────────────────────────────────────────────────────────┤
+│ npx -y @modelcontextprotocol/server-everything    [Copy]│
+├─────────────────────────────────────────────────────────┤
+│ [Server Info]                          [Edit] [Remove]  │


And of course there is Auth related settings that could be set per server: Client ID, Client Secret, Scope.

cliffhall · 2025-12-02T19:41:27Z

specification/v2_ux.md

+    * [Server List (Home)](#server-list-home)
+    * [Server Connection Card](#server-connection-card)
+    * [Import server.json Modal](#import-serverjson-modal)
+    * [Server Info (Connected)](#server-info-connected)


We should also have an OAuth debugger screen or modal.

cliffhall · 2025-12-02T19:42:36Z

specification/v2_ux.md

+```
+┌─────────────────────────────────────────────────────────┐
+│ [Icon] Server Name              v1.0.0                  │
+│        STDIO                    [●] Connected  [Toggle] │


There should be a [OAuth Debug] button that would open a modal or go to a screen for stepping through the oauth flow.

cliffhall · 2025-12-02T19:52:53Z

specification/v2_ux.md

+├─────────────────────────────────────────────────────────┤
+│ npx -y @modelcontextprotocol/server-everything    [Copy]│
+├─────────────────────────────────────────────────────────┤
+│ [Server Info]                          [Edit] [Remove]  │


Also, how to choose connection type is maybe a server specific thing. If the server has its CORS open then you can connect direct, otherwise you'll want to connect via proxy. Maybe this is a dropdown option on this card.

olaservo and others added 3 commits November 29, 2025 21:18

cliffhall requested changes Dec 2, 2025

View reviewed changes

cliffhall reviewed Dec 2, 2025

View reviewed changes

This comment was marked as outdated.

Sign in to view

V2 Spec Additions #945

Are you sure you want to change the base?

V2 Spec Additions #945

Conversation

olaservo commented Nov 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cliffhall left a comment

Choose a reason for hiding this comment

Uh oh!

cliffhall Dec 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as outdated.

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

olaservo commented Nov 30, 2025 •

edited

Loading

cliffhall Dec 2, 2025 •

edited

Loading